home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / p_man / cat3 / sat_read_file_info.z / sat_read_file_info
Text File  |  1998-10-20  |  15KB  |  199 lines
  1.  
  2.  
  3.  
  4. SSSSAAAATTTT____RRRREEEEAAAADDDD____FFFFIIIILLLLEEEE____IIIINNNNFFFFOOOO((((3333CCCC))))                                  SSSSAAAATTTT____RRRREEEEAAAADDDD____FFFFIIIILLLLEEEE____IIIINNNNFFFFOOOO((((3333CCCC))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      sat_read_file_info, sat_write_file_info, sat_free_file_info - Portable
  10.      interfaces to read audit file headers
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssaaaatttt....hhhh>>>>
  14.  
  15.      iiiinnnntttt ssssaaaatttt____rrrreeeeaaaadddd____ffffiiiilllleeee____iiiinnnnffffoooo ((((FFFFIIIILLLLEEEE ****iiiinnnn,,,, FFFFIIIILLLLEEEE ****oooouuuutttt,,,, ssssttttrrrruuuucccctttt ssssaaaatttt____ffffiiiilllleeee____iiiinnnnffffoooo
  16.           ****ffffhhhheeeeaaaaddddeeeerrrr,,,, iiiinnnntttt mmmmaaaasssskkkk))));;;;
  17.  
  18.      iiiinnnntttt ssssaaaatttt____wwwwrrrriiiitttteeee____ffffiiiilllleeee____iiiinnnnffffoooo ((((FFFFIIIILLLLEEEE ****oooouuuutttt,,,, ssssttttrrrruuuucccctttt ssssaaaatttt____ffffiiiilllleeee____iiiinnnnffffoooo ****ffffhhhheeeeaaaaddddeeeerrrr))));;;;
  19.  
  20.      vvvvooooiiiidddd ssssaaaatttt____ffffrrrreeeeeeee____ffffiiiilllleeee____iiiinnnnffffoooo ((((ssssttttrrrruuuucccctttt ssssaaaatttt____ffffiiiilllleeee____iiiinnnnffffoooo ****ffffhhhheeeeaaaaddddeeeerrrr))));;;;
  21.  
  22. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  23.      ssssaaaatttt____rrrreeeeaaaadddd____ffffiiiilllleeee____iiiinnnnffffoooo reads an audit file header into a convenient struct
  24.      for examining its contents.  Translation from older versions of audit
  25.      files is handled transparently by the library routines.  The file header
  26.      is read from file descriptor _i_n and processed into the _f_h_e_a_d_e_r struct.
  27.      If _o_u_t is non-NULL, the data read from _i_n is written back to _o_u_t.  The
  28.      data written is the disk image, not a processed struct.
  29.  
  30.      The ssssaaaatttt____ffffiiiilllleeee____iiiinnnnffffoooo structure pointed to by fheader includes the following
  31.      fields:
  32.  
  33.           iiiinnnntttt     ssssaaaatttt____mmmmaaaajjjjoooorrrr;;;;          ////**** vvvveeeerrrrssssiiiioooonnnn ooooffff aaaauuuuddddiiiitttt ddddaaaattttaaaa ****////
  34.           iiiinnnntttt     ssssaaaatttt____mmmmiiiinnnnoooorrrr;;;;
  35.           ttttiiiimmmmeeee____tttt  ssssaaaatttt____ssssttttaaaarrrrtttt____ttttiiiimmmmeeee;;;;     ////**** ttttiiiimmmmeeee hhhheeeeaaaaddddeeeerrrr wwwwrrrriiiitttttttteeeennnn ****////
  36.           ttttiiiimmmmeeee____tttt  ssssaaaatttt____ssssttttoooopppp____ttttiiiimmmmeeee;;;;      ////**** ttttiiiimmmmeeee ffffiiiilllleeee cccclllloooosssseeeedddd ****////
  37.           lllloooonnnngggg    ssssaaaatttt____hhhhoooosssstttt____iiiidddd;;;;        ////**** hhhhoooosssstttt iiiidddd ****////
  38.           iiiinnnntttt     ssssaaaatttt____mmmmaaaacccc____eeeennnnaaaabbbblllleeeedddd;;;;    ////**** bbbboooooooolllleeeeaaaannnn:::: iiiiggggnnnnoooorrrreeee mmmmaaaacccc ffffiiiieeeellllddddssss???? ****////
  39.           cccchhhhaaaarrrr    ****ssssaaaatttt____ttttiiiimmmmeeeezzzzoooonnnneeee;;;;      ////**** """"TTTTZZZZ====((((ttttiiiimmmmeeeezzzzoooonnnneeee))))"""" ****////
  40.           cccchhhhaaaarrrr    ****ssssaaaatttt____hhhhoooossssttttnnnnaaaammmmeeee;;;;      ////**** hhhhoooossssttttnnnnaaaammmmeeee ****////
  41.           cccchhhhaaaarrrr    ****ssssaaaatttt____ddddoooommmmaaaaiiiinnnnnnnnaaaammmmeeee;;;;    ////**** ddddoooommmmaaaaiiiinnnnnnnnaaaammmmeeee ****////
  42.           iiiinnnntttt     ssssaaaatttt____ffffhhhhddddrrrrssssiiiizzzzeeee;;;;       ////**** nnnnoooo.... ooooffff bbbbyyyytttteeeessss iiiinnnn ddddiiiisssskkkk iiiimmmmaaaaggggeeee ****////
  43.           cccchhhhaaaarrrr    ****ssssaaaatttt____bbbbuuuuffffffffeeeerrrr;;;;        ////**** bbbbuuuuffffffffeeeerrrr wwww////ddddiiiisssskkkk iiiimmmmaaaaggggeeee ooooffff hhhheeeeaaaaddddeeeerrrr ****////
  44.           iiiinnnntttt     ssssaaaatttt____uuuusssseeeerrrr____eeeennnnttttrrrriiiieeeessss;;;;   ////**** nnnnuuuummmmbbbbeeeerrrr ooooffff ssssaaaatttt____lllliiiisssstttt____eeeennnntttt ssssttttrrrruuuuccccttttssss ****////
  45.           iiiinnnntttt     ssssaaaatttt____ggggrrrroooouuuupppp____eeeennnnttttrrrriiiieeeessss;;;;  ////**** iiiinnnn tttthhhheeee uuuusssseeeerrrr,,,, ggggrrrroooouuuupppp,,,, aaaannnndddd ****////
  46.           iiiinnnntttt     ssssaaaatttt____hhhhoooosssstttt____eeeennnnttttrrrriiiieeeessss;;;;   ////**** tttthhhheeee hhhhoooossssttttiiiidddd <<<<---->>>> nnnnaaaammmmeeee lllliiiisssstttt ****////
  47.           ssssttttrrrruuuucccctttt ssssaaaatttt____lllliiiisssstttt____eeeennnntttt ********ssssaaaatttt____uuuusssseeeerrrrssss;;;;    ////**** uuuusssseeeerrrr eeeennnnttttrrrriiiieeeessss ****////
  48.           ssssttttrrrruuuucccctttt ssssaaaatttt____lllliiiisssstttt____eeeennnntttt ********ssssaaaatttt____ggggrrrroooouuuuppppssss;;;;   ////**** ggggrrrroooouuuupppp eeeennnnttttrrrriiiieeeessss ****////
  49.           ssssttttrrrruuuucccctttt ssssaaaatttt____lllliiiisssstttt____eeeennnntttt ********ssssaaaatttt____hhhhoooossssttttssss;;;;    ////**** hhhhoooossssttttiiiidddd eeeennnnttttrrrriiiieeeessss ****////
  50.  
  51.      Due to the format that the file header is read from disk, several fields
  52.      in the file header require extra computation and memory.  To allow the
  53.      user to select only the fields they are interested in, there is a _m_a_s_k
  54.      which specifies which fields to include.  These are:
  55.  
  56.           SFI_NONE       Include none of the extra fields.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SSSSAAAATTTT____RRRREEEEAAAADDDD____FFFFIIIILLLLEEEE____IIIINNNNFFFFOOOO((((3333CCCC))))                                  SSSSAAAATTTT____RRRREEEEAAAADDDD____FFFFIIIILLLLEEEE____IIIINNNNFFFFOOOO((((3333CCCC))))
  71.  
  72.  
  73.  
  74.           SFI_TIMEZONE   Include sat_timezone from the file header.
  75.  
  76.           SFI_HOSTNAME   Include sat_hostname from the file header.
  77.  
  78.           SFI_DOMNAME    Include sat_domainname from the file header.
  79.  
  80.           SFI_USERS      Include an array of sat_list_ent structs containing
  81.                          user name <-> user id mappings.
  82.  
  83.           SFI_GROUPS     Above, for group name <-> group id mappings.
  84.  
  85.           SFI_HOSTS      Above, for host name <-> host id mappings.
  86.  
  87.           SFI_BUFFER     Include the original disk image of the file header.
  88.  
  89.           SFI_ALL        Include everything.
  90.  
  91.      Note that the timezone field has TZ= prepended to make a call to
  92.      ppppuuuutttteeeennnnvvvv(3C).  If this is not the intended use of the string, remember to
  93.      account for the extra three characters.
  94.  
  95.      The user and group lists in particular require a fair amount of
  96.      computation and memory allocation to provide.  If a field is not
  97.      requested in the mask, the value in fheader will be NULL.  To specify
  98.      combinations of the above masks, simply "or" them together, like so:
  99.  
  100.           ((((SSSSFFFFIIII____TTTTIIIIMMMMEEEEZZZZOOOONNNNEEEE |||| SSSSFFFFIIII____HHHHOOOOSSSSTTTTNNNNAAAAMMMMEEEE |||| SSSSFFFFIIII____DDDDOOOOMMMMNNNNAAAAMMMMEEEE))))
  101.  
  102.      There are three ways to write out a file header that has been read in.
  103.      The first and easiest is to specify a file descriptor _o_u_t in the
  104.      ssssaaaatttt____rrrreeeeaaaadddd____ffffiiiilllleeee____iiiinnnnffffoooo call.  If output is not required, use NULL for this
  105.      value.  The second method is to ask for the disk image using SSSSFFFFIIII____BBBBUUUUFFFFFFFFEEEERRRR
  106.      in the mask.  When output is desired, use ffffwwwwrrrriiiitttteeee(3C) to write the
  107.      contents of ssssaaaatttt____bbbbuuuuffffffffeeeerrrr to disk.  The length of the data in ssssaaaatttt____bbbbuuuuffffffffeeeerrrr is
  108.      in ssssaaaatttt____ffffhhhhddddrrrrssssiiiizzzzeeee.  The third method is to call ssssaaaatttt____wwwwrrrriiiitttteeee____ffffiiiilllleeee____iiiinnnnffffoooo, which
  109.      is more computationally expensive, and can only be used for the most
  110.      current file version.  Calling ssssaaaatttt____wwwwrrrriiiitttteeee____ffffiiiilllleeee____iiiinnnnffffoooo is only advisable if
  111.      some data in the header has been changed.
  112.  
  113.      ssssaaaatttt____ffffrrrreeeeeeee____ffffiiiilllleeee____iiiinnnnffffoooo is used to free any data that ssssaaaatttt____rrrreeeeaaaadddd____ffffiiiilllleeee____iiiinnnnffffoooo
  114.      allocated while constructing a ssssaaaatttt____ffffiiiilllleeee____iiiinnnnffffoooo struct.  It does not free
  115.      the struct itself, only certain fields within the struct.  To make sure
  116.      the struct isn't used afterwards, it is zeroed after all the fields are
  117.      freed.
  118.  
  119. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  120.      ssssaaaatttt____rrrreeeeaaaadddd____ffffiiiilllleeee____iiiinnnnffffoooo returns SSSSFFFFIIII____OOOOKKKKAAAAYYYY on success, SSSSFFFFIIII____WWWWAAAARRRRNNNNIIIINNNNGGGG if there was
  121.      no file header to be read, or SSSSFFFFIIII____EEEERRRRRRRROOOORRRR if any errors were detected.
  122.  
  123.      ssssaaaatttt____wwwwrrrriiiitttteeee____ffffiiiilllleeee____iiiinnnnffffoooo returns SSSSFFFFIIII____OOOOKKKKAAAAYYYY on success, or SSSSFFFFIIII____EEEERRRRRRRROOOORRRR if any
  124.      errors were detected.
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SSSSAAAATTTT____RRRREEEEAAAADDDD____FFFFIIIILLLLEEEE____IIIINNNNFFFFOOOO((((3333CCCC))))                                  SSSSAAAATTTT____RRRREEEEAAAADDDD____FFFFIIIILLLLEEEE____IIIINNNNFFFFOOOO((((3333CCCC))))
  137.  
  138.  
  139.  
  140.      Error messages are also written to stderr.  If an error occurrs, it may
  141.      be useful to check ffffeeeeooooffff(3S) and ffffeeeerrrrrrrroooorrrr(3S) on the file descriptors for
  142.      further diagnostics.
  143.  
  144. NNNNOOOOTTTTEEEE
  145.      If _o_u_t is specified to ssssaaaatttt____rrrreeeeaaaadddd____ffffiiiilllleeee____iiiinnnnffffoooo, no checks are done on the
  146.      write performed.  It is recommended that the user check ffffeeeerrrrrrrroooorrrr(3S) on the
  147.      file descriptor to make sure it was written successfully.  Output error
  148.      checking is performed for ssssaaaatttt____wwwwrrrriiiitttteeee____ffffiiiilllleeee____iiiinnnnffffoooo.
  149.  
  150. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  151.      ffffooooppppeeeennnn(3S), ffffcccclllloooosssseeee(3S), ffffeeeeooooffff(3S), ssssaaaatttt____rrrreeeeaaaadddd____hhhheeeeaaaaddddeeeerrrr____iiiinnnnffffoooo(3C),
  152.      ssssaaaatttt____ffffrrrreeeeeeee____hhhheeeeaaaaddddeeeerrrr____iiiinnnnffffoooo(3C), ssssaaaatttt____iiiinnnnttttrrrrpppp____ppppaaaatttthhhhnnnnaaaammmmeeee(3C).
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.